Introduction  ReStructuredText
===============================

:Auteur: Richard Jones
:Version: 1.10
:Traduction: William Dode <wilk *at* flibuste.net>

.. contents::


Ce texte contient des liens de la forme "(quickref__)".  Ils sont
relatifs au manuel de rfrence utilisateur `Quick reStructuredText`_.
S'ils ne fonctionnent pas, rfrez vous au document `master quick
reference`_.

__ 
.. _Quick reStructuredText: http://docutils.sourceforge.net/docs/rst/quickref.html
.. _master quick reference: 
   http://docutils.sourceforge.net/docs/rst/quickref.html


Structure
---------

Pour commencer, il me semble que "Structured Text" n'est pas tout  fait la
bonne appellation. Nous devrions plutt le nommer "Relaxed Text" qui contient
quelques schmas logiques. Ces schmas sont interprts par un convertisseur
HTML pour produire "Very Structured Text" (un texte trs structur) qui pourra
tre utilis par un navigateur web.

Le schma le plus simple est le **paragraphe** (quickref__).
C'est un bloc de texte spar par des lignes vides (une seule suffit).
Les paragraphes doivent avoir le mme dcalage -- c'est  dire des espaces
 gauche. Ces paragraphes produiront un texte dcal. Par exemple::

  Ceci est un paragraphe.
  Trs court.

     Le texte de ce paragraphe sera dcal,
     gnralement utilis pour des citations.

  En voil un autre

Le rsultat donne :

  Ceci est un paragraphe.
  Trs court.

     Le texte de ce paragraphe sera dcal,
     gnralement utilis pour des citations.

  En voil un autre
  
__ http://docutils.sourceforge.net/docs/rst/quickref.html#paragraphs

Styles de texte
---------------

(quickref__)

__ http://docutils.sourceforge.net/docs/rst/quickref.html#inline-markup

Dans les paragraphes et le corps du texte, nous pouvons utiliser
des marqueurs pour *italique* avec "``*italique*``" ou **gras**
avec "``**gras**``".

Si l'on souhaite qu'un texte apparaisse dans une police  chasse
fixe "````doubles apostrophes inverses````". 
Notez qu'aucun traitement supplmentaire n'est apport entre deux
doubles apostrophes inverses -- les astrisques, comme dans "``*``",
sont donc conserves en l'tat.

Si vous souhaitez utiliser un de ces caractres "spciaux" dans
le texte, il n'y a gnralement pas de problme -- reStructuredText
est assez malin.
Par exemple, cet astrisque * est trait correctement. Si vous
souhaitez par contre \*entourer un texte par des astrisques* 
**sans** qu'il soit en italique, il est ncessaire d'indiquer que
l'astrisque ne doit pas tre interprt. Pour cela il suffit de placer
une barre oblique inverse juste avant lui, comme a "``\*``" (quickref__), ou
en l'entourant de doubles apostrophes inverses (litteral), comme cela ::

  ``\*``

__ http://docutils.sourceforge.net/docs/rst/quickref.html#escaping

Listes
------

Il y a trois types de listes: **numrotes**, **avec puces** et
de **dfinitions**. Dans chaque cas, nous pouvons avoir autant
de paragraphes, sous-listes, etc. que l'on souhaite, tant que
le dcalage  gauche est align sur la premire ligne.

Les listes doivent toujours dmarrer un nouveau paragraphe
-- c'est  dire qu'il doit y avoir un saut de ligne juste avant.

Listes **numrotes** (par des nombres, lettres, chiffres romains;
quickref__)

__ http://docutils.sourceforge.net/docs/rst/quickref.html#enumerated-lists

  En dmarrant une ligne avec un numro ou une lettre suivie d'un
  point ".", une parenthse droite ")" ou entour par des parenthses
  -- comme vous prfrez. Toutes ces formes sont reconnues::

    1. nombres

    A. Lettres en majuscule
       qui continue sur plusieurs ligne

       avec deux paragraphes et tout !

    a. lettres minuscules

       3. avec une sous-liste qui dmarre  un nombre diffrent
       4. faites attention  garder une squence de nombre correcte !

    I. majuscules en chiffres romains

    i. minuscules en chiffres romains

    (1) des nombres  nouveau

    1) et encore

  Le rsultat (note : Tous les styles de listes ne sont pas toujours
  supports par tous les navigateurs, vous ne verrez donc pas forcment
  les effets complets) :

    1. nombres

    A. Lettres en majuscule
       qui continue sur plusieurs ligne

       avec deux paragraphes et tout !

    a. lettres minuscules

       3. avec une sous-liste qui dmarre  un nombre diffrent
       4. faites attention  garder une squence de nombre correcte !

    I. majuscules en chiffres romains

    i. minuscules en chiffres romains

    (1) des nombres  nouveau

    1) et encore

Listes ** puces** (quickref__)

__ http://docutils.sourceforge.net/docs/rst/quickref.html#bullet-lists

  De la mme manire que pour les listes numrotes, il faut dmarrer
  la premire ligne avec une puce -- soit "-", "+" ou "*"::

    * une puce "*"

      - une sous-liste avec "-"

         +  nouveau une sous-liste

      - une autre option

  Le rsultat:

    * une puce "*"

      - une sous-liste avec "-"

         +  nouveau une sous-liste

      - une autre option

Les listes de **dfinitions** (quickref__)

__ http://docutils.sourceforge.net/docs/rst/quickref.html#definition-lists

  Comme les deux autres, les listes de dfinitions consistent en un
  terme et la dfinition de ce terme. Le format est le suivant::

    Quoi
      Les listes de dfinitions associent un terme avec une dfinition.

    *Comment*
      Le terme est une phrase d'une ligne, et la dfinition est d'un
      ou plusieurs paragraphes ou lments, dcals par rapport au terme.
      Les lignes vides ne sont pas autorises entre le terme et la dfinition.

  Le rsultat:

    Quoi
      Les listes de dfinitions associent un terme avec une dfinition.

    *Comment*
      Le terme est une phrase d'une ligne, et la dfinition est d'un
      ou plusieurs paragraphes ou lments, dcals par rapport au terme.
      Les lignes vides ne sont pas autorises entre le terme et la dfinition.

Prformatage
-------------
(quickref__)

__ http://docutils.sourceforge.net/docs/rst/quickref.html#literal-blocks

Pour inclure un texte prformat sans traitement
il suffit de terminer le paragraphe par "``::``". Le texte prformat est
termin lorsqu'une ligne retombe au niveau du dcalage prcdent. Par exemple::

  Un exemple::

      Espaces, nouvelles lignes, lignes vides, et toutes sortes de marqueurs
         (comme *ceci* ou \cela) sont prservs dans les bloc prformats.

   Regardez ici, je suis descendu d'un niveau.
   (mais pas assez)

  Fin de l'exemple

Le rsultat:

  Un exemple::

      Espaces, nouvelles lignes, lignes vides, et toutes sortes de marqueurs
         (comme *ceci* ou \cela) sont prservs dans les bloc prformats.

   Regardez ici, je suis descendu d'un niveau.
   (mais pas assez)

  Fin de l'exemple

Notez que si le paragraphe contient seulement "``::``", il est ignor.

  ::

     Ceci est un texte prformat,
     le paragraphe "::" est ignor.

Sections
--------
(quickref__)

__ http://docutils.sourceforge.net/docs/rst/quickref.html#section-structure

Pour diviser un texte en plusieurs sections, nous utilisons des
**en-ttes de section**. C'est  dire une seule ligne de texte (d'un
ou plusieurs mots) avec un ornement : juste en dessous et ventuellement
dessus aussi, avec des tirets "``-----``", gal "``=====``", tildes
"``~~~~~``" ou n'importe quel de ces caractres ``= - ` : ' " ~ ^ _ * + # < >``
qui vous semble convenir. Un ornement simplement en dessous n'a pas la
mme signification qu'un ornement dessus-dessous avec le mme caractre.
Les ornements doivent avoir au moins la taille du texte. Soyez cohrent,
les ornements identiques sont censs tre du mme niveau::

  Chapitre 1
  ==========

  Section 1.1
  -----------

  Sous-section 1.1.1
  ~~~~~~~~~~~~~~~~~~

  Section 1.2
  -----------

  Chapitre 2
  ==========

Le rsultat de cette structure, sous la forme pseudo-XML::

    <section>
        <title>
            Chapitre 1
        <section>
            <title>
                Section 1.1
            <section>
                <title>
                    Sous-section 1.1.1
        <section>
            <title>
                Section 1.2
    <section>
        <title>
            Chapitre 2
  
(Pseudo-XML utilise une indentation et n'as pas de balises finale. Il
n'est pas possible de montrer le rsultat, comme dans les autres exemples,
du fait que les sections ne peuvent tre utilises  l'intrieur d'un
paragraphe dcal. Pour un exemple concret, comparez la structure de
ce document avec le rsultat.)

Notez que les en-ttes de section sont utilisable comme cible de liens,
simplement en utilisant leur nom. Pour crer un lien sur la section Listes_,
j'cris "``Listes_``". Si le titre comporte des espaces, il est ncessaire
d'utiliser les doubles apostrophes inverses "```Styles de texte`_``".

Pour indiquer le titre du document, utilisez un style d'ornement unique
en dbut de document. Pour indiquer un sous-titre de document, utilisez
un autre ornement unique juste aprs le titre.
Par exemple::

    =================
    Titre du document
    =================
    ----------
    Sous-titre
    ----------

    Titre de la section
    ===================

    ...

Notez que "Titre du document" et "Titre de la section" utilisent le signe
gal, mais sont diffrents et sans relation. Le texte et l'ornement peuvent
tre de la mme taille pour des questions d'esthtisme.


Images
------
(quickref__)

__ http://docutils.sourceforge.net/docs/rst/quickref.html#directives

Pour inclure une image dans votre document, vous devez utiliser la directive__
``image``.
Par exemple::

    .. image:: images/biohazard.png

Le rsultat:

.. image:: images/biohazard.png

La partie ``images/biohazard.png`` indique le chemin d'accs au fichier
de l'image qui doit apparatre. Il n'y a pas de restriction sur l'image
(format, taille etc). Si l'image doit apparatre en HTML et que vous
souhaitez lui ajouter des informations::

  .. image:: images/biohazard.png
     :height: 100
     :width: 200
     :scale: 50
     :alt: texte alternatif

Consultez la documentation__ complte de la directive image pour plus d'informations.

__ ../../spec/rst/directives.html
__ ../../spec/rst/directives.html#images


Et ensuite ?
------------

Cette introduction montre les possibilits les plus courantes de reStructuredText,
mais il y en a bien d'autres  explorer. Le manuel de rfrence utilisateur
'Quick reStructuredText`_ est recommand pour aller plus loin. Pour les dtails complets
consultez `reStructuredText Markup Specification`_ [#]_.

Les utilisateurs ayant besoin d'aide avec Docutils ou reStructuredText peuvent
`poster un message`_ sur la liste de diffusion `Docutils-Users mailing list`_.
Le `Docutils project web site`_ comporte davantage d'informations.

.. [#] Si ce lien relatif ne fonctionne pas, consultez le document principal:
   http://docutils.sourceforge.net/spec/rst/reStructuredText.html.

.. _reStructuredText Markup Specification:
   ../../spec/rst/reStructuredText.html
.. _poster un message: mailto:docutils-users@lists.sourceforge.net
.. _Docutils-Users mailing list:
   http://lists.sourceforge.net/lists/listinfo/docutils-users
.. _Docutils project web site: http://docutils.sourceforge.net/
